home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / funnel.zoo / sources / list.h < prev    next >
C/C++ Source or Header  |  1993-04-11  |  12KB  |  208 lines
  1. /*##############################################################################
  2.  
  3. FUNNNELWEB COPYRIGHT
  4. ====================
  5. FunnelWeb is a literate-programming macro preprocessor.
  6.  
  7. Copyright (C) 1992 Ross N. Williams.
  8.  
  9.    Ross N. Williams
  10.    ross@spam.adelaide.edu.au
  11.    16 Lerwick Avenue, Hazelwood Park 5066, Australia.
  12.  
  13. This program is free software; you can redistribute it and/or modify
  14. it under the terms of Version 2 of the GNU General Public License as
  15. published by the Free Software Foundation.
  16.  
  17. This program is distributed WITHOUT ANY WARRANTY; without even the implied
  18. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  19. See Version 2 of the GNU General Public License for more details.
  20.  
  21. You should have received a copy of Version 2 of the GNU General Public
  22. License along with this program. If not, you can FTP the license from
  23. prep.ai.mit.edu/pub/gnu/COPYING-2 or write to the Free Software
  24. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  
  26. Section 2a of the license requires that all changes to this file be
  27. recorded prominently in this file. Please record all changes here.
  28.  
  29. Programmers:
  30.    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  31.  
  32. Changes:
  33.    07-May-1992  RNW  Program prepared for release under GNU GPL V2.
  34.  
  35. ##############################################################################*/
  36.  
  37.  
  38. /******************************************************************************/
  39. /*                                  LIST.H                                    */
  40. /******************************************************************************/
  41. /*                                                                            */
  42. /* Introduction                                                               */
  43. /* ------------                                                               */
  44. /* This list package (list.h and list.c) implements a list abstraction.       */
  45. /*                                                                            */
  46. /* Facts about Lists                                                          */
  47. /* -----------------                                                          */
  48. /* - A LIST stores zero or more LIST ELEMENTS.                                */
  49. /* - The user decides the type of element to be stored in each list.          */
  50. /* - Each list stores only one type of list element; lists are homogeneous.   */
  51. /* - Lists store copies of elements rather than pointers to elements.         */
  52. /* - Each list can hold from zero to about 2^31 elements.                     */
  53. /* - Each list has a HEAD end and a TAIL end.                                 */
  54. /* - Elements can be appended and deleted only at the tail of the list.       */
  55. /* - The elements of a list can be read sequentially from head to tail.       */
  56. /* - A MARKER stores the current position in the list for sequential reading. */
  57. /* - Upon list creation, the marker is positioned at the tail of the list.    */
  58. /* - In a list of n elements, elements are numbered from 1 to n.              */
  59. /* - Element 1 is at the head of the list. Element n is at the tail.          */
  60. /* - The identifier "ls" is used as an abbreviation for "list".               */
  61. /* - The identifier "el" is used as an abbreviation for "element".            */
  62. /* - Longer names are desirable, but shorter ones have been used so as to     */
  63. /*   enhance the portability of the package.                                  */
  64. /* - IMPORTANT: Lists get all their memory using mm_temp calls.               */
  65. /*                                                                            */
  66. /* How To Use This List Package                                               */
  67. /* ----------------------------                                               */
  68. /* 1. Include this .H file in your program file.                              */
  69. /* 2. Identify the type of elements to be placed in the list.                 */
  70. /* 3. Define a variable of type p_ls as a view to a list.                     */
  71. /* 4. Use the ls_* functions to perform the desired operations.               */
  72. /*    Start with a call to ls_cre and (optionally) end with a call to ls_des. */
  73. /*                                                                            */
  74. /******************************************************************************/
  75.  
  76. /* Ensure that the body of this header file is included at most once.         */
  77. #ifndef DONE_LIST
  78. #define DONE_LIST
  79.  
  80. /******************************************************************************/
  81.  
  82. #include "style.h"
  83.  
  84. /******************************************************************************/
  85.  
  86. /* Users manipulate lists through pointers to lists (p_ls_t). The following   */
  87. /* declaration serves the list user of the package while hiding the           */
  88. /* implementation details (which appear in a similar declaration in list.c).  */
  89. /* The #ifndef stops list.c from seeing these public declarations.            */
  90. #ifndef INLISTC
  91. typedef struct {word NEVER_USE_THIS_FIELD_UQJTKC;} ls_yqwx; /* Don't use! */
  92. typedef ls_yqwx *p_ls_t;
  93. typedef p_void p_lsel_t;
  94. typedef p_lsel_t *pp_lsel_t;
  95. #endif
  96.  
  97. /******************************************************************************/
  98. /*                                                                            */
  99. /* General Notes About These Functions                                        */
  100. /* -----------------------------------                                        */
  101. /* - All lists and elements are passed by pointer. Whether a parameter is     */
  102. /*   read or written is determined by it's function's description.            */
  103. /* - Each function (except ls_cre) accepts a single pointer to a list and     */
  104. /*   each function's description is assumed to be referring to the list.      */
  105. /* - "Raising an error" means calling the external function "error" to        */
  106. /*   write out a message and bomb the program.                                */
  107. /* - You must create a list using ls_cre before performing any operations     */
  108. /*   upon it. A list function will usually raise an error if it is            */
  109. /*   handed a pointer that does not point to a properly CREated list.         */
  110. /*                                                                            */
  111. /* WARNING: This package copies values into its internal data structures      */
  112. /* (through ls_add), but returns only POINTERS to elements when asked to      */
  113. /* retrieve them. These pointers are valid only so long as the element        */
  114. /* that they point to remains in the list. If the element is deleted somehow, */
  115. /* the pointer points to garbage and becomes dangerous.                       */
  116. /* So, if you have been handed a pointer to an element in a list (ls_nxt,     */
  117. /* ls_loo), do not subsequently delete the element (ls_lop, ls_emp, ls_des)   */
  118. /* and then attempt to access the element through the pointer.                */
  119. /* One sure way to avoid the problem is always to use the pointer handed back */
  120. /* by ls_nxt or ls_loo to copy the element immediately.                       */
  121.  
  122. /* The Functions                                                              */
  123. /* -------------                                                              */
  124. EXPORT p_ls_t ls_cre P_((size_t));
  125. /* CREate. Creates a new list and returns a pointer to the new list. The user */
  126. /* must specify in the parameter the size of elements that are to be stored   */
  127. /* in the list. Specify the size of elements in bytes (usually using sizeof). */
  128. /* The sequential reading marker is set to position n+1=1=tail of the list.   */
  129.  
  130. EXPORT void ls_add P_((p_ls_t,p_lsel_t));
  131. /* ADD. Adds a new element onto the tail of the list (at position n+1).       */
  132. /* The user must supply in the second parameter a pointer to the element to   */
  133. /* be added. ls_add takes a copy of the element (it knows from the earlier    */
  134. /* call to ls_cre how many bytes to copy) and stores the copy in its own      */
  135. /* internal data structures.                                                  */
  136.